Add AGENTS files #609

dgarros · 2025-11-09T17:10:34Z

This PR adds a few AGENTS.md files across the repository to help AI Agents work on the project.
This is really a starting point and I would expect us to modify them heavily as we really start to use them

Here is the main prompt I use to generate these files in Cursor.

You are a code-analysis and documentation-generation agent.

Your mission is to analyze this repository and implement AGENTS.md files following the open standard described here:
- https://layer5.io/blog/ai/agentsmd-one-file-to-guide-them-all
- https://agents.md/#examples

Your tasks:

1. **Repository Scan**
   - Recursively scan the entire repository.
   - Identify any existing agent instruction files, such as:
     - `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/rules.mdc`
     - Any AI assistant configuration (e.g., Copilot, Claude, Cursor, etc.)
   - Output a concise report with each file’s path and a short summary of its content or intent.

2. **Relevance Analysis**
   - Analyze the repo structure to detect *logical modules or contexts* that would benefit from their own agent guidance.
     - Typical examples: `/docs`, `/tests`, `/api`, `/frontend`, `/backend`, `/cli`, `/scripts`, `/infra`, etc.
   - Do **not** create redundant AGENTS.md files everywhere.
   - Only create them where:
     - The subdirectory contains distinct code or documentation domains.
     - The conventions or expectations differ from the root-level project.
     - An agent working in isolation in that subfolder might need specific guidance.

3. **Generate / Update AGENTS.md**
   - Generate or update:
     - A **root-level `AGENTS.md`** as the main entry point (the “source of truth”).
     - Additional **context-specific `AGENTS.md`** files in selected directories identified above.
   - Each file must follow the AGENTS.md standard, and include (as applicable):
     - **Purpose & Context** (what this directory/project area is for)
     - **Tech Stack / Dependencies**
     - **Code Conventions & Standards**
     - **Build / Test / Linting Instructions**
     - **Relevant Tools or Libraries**
     - **How AI agents should contribute or avoid errors**
     - **Interplay with parent modules** (link to main AGENTS.md)
     - **Common pitfalls or edge cases**
   - Cross-reference related AGENTS.md files using relative Markdown links.

4. **Integration & Deduplication**
   - If older instruction/config files exist for specific agents (Claude, Copilot, etc.):
     - Consolidate their content into the new AGENTS.md structure.
     - Leave a short redirect or comment in old files pointing to the unified AGENTS.md.
     - Avoid duplicating information.

5. **Output**
   - Print:
     - A summary table listing each generated or updated AGENTS.md file (with relative paths).
     - The content of each new file in full.
     - A brief justification for why that directory was chosen (based on structure, code type, or unique conventions).

6. **Quality & Formatting**
   - Use clean, readable Markdown.
   - Keep each section concise and informative.
   - Use consistent heading levels (`##`, `###`) across all generated files.
   - Ensure cross-references between AGENTS.md files work properly.

Goal: create a cohesive AGENTS.md ecosystem that helps AI coding assistants (Cursor, Claude, Copilot, etc.) understand and operate safely and productively within this repository.

Begin by scanning and analyzing the repository structure.

coderabbitai · 2025-11-09T17:10:42Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (4)

main
stable
develop
release-.*

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch dga-20251109-agents

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cloudflare-workers-and-pages · 2025-11-09T17:26:08Z

Deploying infrahub-sdk-python with Cloudflare Pages

Latest commit:	`b07995c`
Status:	✅ Deploy successful!
Preview URL:	https://143f020a.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://dga-20251109-agents.infrahub-sdk-python.pages.dev

View logs

… frontmatter Fix Vale linting errors in docs/AGENTS.md by adding valid terms to spelling exceptions: - Diataxis: Documentation framework name - Typer: Python CLI library name - callouts: Documentation component term - frontmatter: MDX frontmatter term This resolves the CI failures in PR #609.

ogenstad · 2025-11-10T11:43:16Z

AGENTS.md

+
+### Core Technologies
+
+- **Python**: 3.9-3.13 (see `pyproject.toml` for exact version requirements)


Here we specifically mention that pyproject.toml should be consulted for exact version requirements for Python. I'm wondering if we should instead do that for all of the other requirements, i.e. instead of hardcoding mypy, ruff and all other dependencies to fixed versions or current ranges. I feel it's something that will be hard to keep up to date and end up providing obsolete instructions.

ogenstad · 2025-11-10T11:48:07Z

AGENTS.md

+- **Ruff**: Comprehensive linting and formatting (0.11.0)
+  - Configuration in `pyproject.toml` under `[tool.ruff]`
+  - Line length: 120 (formatter), 150 (pycodestyle)
+  - Max complexity: 17


I think we should lower the complexity for new code and try to start it out at 10.

ogenstad · 2025-11-10T11:49:25Z

AGENTS.md

+# WRONG
+class MyCheck(InfrahubCheck):
+    def check(self, data):  # This will NOT work
+        pass


In all of the examples provided to the agents I think we should use methods with full typing on all parameters and return values.

ogenstad · 2025-11-10T11:54:01Z

AGENTS.md

+│   └── relationship.py # Relationship management
+├── ctl/               # CLI commands (infrahubctl)
+├── pytest_plugin/    # Custom pytest plugin for Infrahub testing
+└── protocols.py       # Generated protocol classes


The comments for these files are aligned in the file in the docs section. I think we should do the same here so it's a bit easier to read.

ogenstad · 2025-11-10T12:01:41Z

LGTM, the main thing I'd update for now is to ensure that all of the code examples are fully typed as that's what we'd expect in any generated code.

… frontmatter Fix Vale linting errors in docs/AGENTS.md by adding valid terms to spelling exceptions: - Diataxis: Documentation framework name - Typer: Python CLI library name - callouts: Documentation component term - frontmatter: MDX frontmatter term This resolves the CI failures in PR #609.

dgarros added 2 commits November 9, 2025 17:08

Convert project to UV

70d0418

Add AGENTS files in a few directories

c3c0a4c

dgarros marked this pull request as ready for review November 9, 2025 17:10

github-actions bot added the type/documentation Improvements or additions to documentation label Nov 9, 2025

dgarros requested review from a team and petercrocker November 9, 2025 17:10

Fix format

36455e5

ogenstad reviewed Nov 10, 2025

View reviewed changes

dgarros force-pushed the dga-20251104-poetry-uv branch 2 times, most recently from e6779d7 to 838fcf6 Compare November 11, 2025 08:33

Base automatically changed from dga-20251104-poetry-uv to develop November 12, 2025 07:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add AGENTS files #609

Add AGENTS files #609

Uh oh!

dgarros commented Nov 9, 2025

Uh oh!

coderabbitai bot commented Nov 9, 2025 •

edited

Loading

Review skipped

Uh oh!

cloudflare-workers-and-pages bot commented Nov 9, 2025 •

edited

Loading

Uh oh!

ogenstad Nov 10, 2025

Uh oh!

ogenstad Nov 10, 2025

Uh oh!

ogenstad Nov 10, 2025

Uh oh!

ogenstad Nov 10, 2025

Uh oh!

ogenstad commented Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		### Core Technologies

		- Python: 3.9-3.13 (see `pyproject.toml` for exact version requirements)

Add AGENTS files #609

Are you sure you want to change the base?

Add AGENTS files #609

Uh oh!

Conversation

dgarros commented Nov 9, 2025

Uh oh!

coderabbitai bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

cloudflare-workers-and-pages bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying infrahub-sdk-python with Cloudflare Pages

Uh oh!

ogenstad Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

ogenstad Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

ogenstad Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

ogenstad Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

ogenstad commented Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Nov 9, 2025 •

edited

Loading

cloudflare-workers-and-pages bot commented Nov 9, 2025 •

edited

Loading